home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
X User Tools
/
X User Tools (O'Reilly and Associates)(1994).ISO
/
sun4c
/
archive
/
tcltk.z
/
tcltk
/
man
/
cat3
/
ParseArgv.3
< prev
next >
Wrap
Text File
|
1994-09-20
|
19KB
|
529 lines
Tk_ParseArgv(3) Tk Library Procedures
_________________________________________________________________
NAME
Tk_ParseArgv - process command-line options
SYNOPSIS
#include <tk.h>
int
Tk_ParseArgv(_i_n_t_e_r_p, _t_k_w_i_n, _a_r_g_c_P_t_r, _a_r_g_v, _a_r_g_T_a_b_l_e, _f_l_a_g_s)
ARGUMENTS
Tcl_Interp *_i_n_t_e_r_p (in) Interpreter to use for
returning error mes-
sages.
Tk_Window _t_k_w_i_n (in) Window to use when argu-
ments specify Tk
options. If NULL, then
no Tk options will be
processed.
int _a_r_g_c_P_t_r (in/out) Pointer to number of
arguments in argv; gets
modified to hold number
of unprocessed arguments
that remain after the
call.
char **_a_r_g_v (in/out) Command line arguments
passed to main program.
Modified to hold unpro-
cessed arguments that
remain after the call.
Tk_ArgvInfo *_a_r_g_T_a_b_l_e (in) Array of argument
descriptors, terminated
by element with type
TK_ARGV_END.
int _f_l_a_g_s (in) If non-zero, then it
specifies one or more
flags that control the
parsing of arguments.
Different flags may be
OR'ed together. The
flags currently defined
are
TK_ARGV_DONT_SKIP_FIRST_ARG,
TK_ARGV_NO_ABBREV,
TK_ARGV_NO_LEFTOVERS,
and TK_ARGV_NO_DEFAULTS.
Tk 1
Tk_ParseArgv(3) Tk Library Procedures
_________________________________________________________________
DESCRIPTION
Tk_ParseArgv processes an array of command-line arguments
according to a table describing the kinds of arguments that
are expected. Each of the arguments in _a_r_g_v is processed in
turn: if it matches one of the entries in _a_r_g_T_a_b_l_e, the
argument is processed according to that entry and discarded.
The arguments that do not match anything in _a_r_g_T_a_b_l_e are
copied down to the beginning of _a_r_g_v (retaining their origi-
nal order) and returned to the caller. At the end of the
call Tk_ParseArgv sets *_a_r_g_c_P_t_r to hold the number of argu-
ments that are left in _a_r_g_v, and _a_r_g_v[*_a_r_g_c_P_t_r] will hold
the value NULL. Normally, Tk_ParseArgv assumes that _a_r_g_v[_0]
is a command name, so it is treated like an argument that
doesn't match _a_r_g_T_a_b_l_e and returned to the caller; however,
if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in _f_l_a_g_s then
_a_r_g_v[_0] will be processed just like the other elements of
_a_r_g_v.
Tk_ParseArgv normally returns the value TCL_OK. If an error
occurs while parsing the arguments, then TCL_ERROR is
returned and Tk_ParseArgv will leave an error message in
_i_n_t_e_r_p->_r_e_s_u_l_t in the standard Tcl fashion. In the event of
an error return, *_a_r_g_v_P_t_r will not have been modified, but
_a_r_g_v could have been partially modified. The possible
causes of errors are explained below.
The _a_r_g_T_a_b_l_e array specifies the kinds of arguments that are
expected; each of its entries has the following structure:
typedef struct {
char*_k_e_y;
int _t_y_p_e;
char*_s_r_c;
char*_d_s_t;
char*_h_e_l_p;
} Tk_ArgvInfo;
The _k_e_y field is a string such as ``-display'' or ``-bg''
that is compared with the values in _a_r_g_v. _T_y_p_e indicates
how to process an argument that matches _k_e_y (more on this
below). _S_r_c and _d_s_t are additional values used in process-
ing the argument. Their exact usage depends on _t_y_p_e, but
typically _s_r_c indicates a value and _d_s_t indicates where to
store the value. The char * declarations for _s_r_c and _d_s_t
are placeholders: the actual types may be different.
Lastly, _h_e_l_p is a string giving a brief description of this
option; this string is printed when users ask for help
about command-line options.
Tk 2
Tk_ParseArgv(3) Tk Library Procedures
When processing an argument in _a_r_g_v, Tk_ParseArgv compares
the argument to each of the _k_e_y's in _a_r_g_T_a_b_l_e. Tk_ParseArgv
selects the first specifier whose _k_e_y matches the argument
exactly, if such a specifier exists. Otherwise Tk_ParseArgv
selects a specifier for which the argument is a unique
abbreviation. If the argument is a unique abbreviation for
more than one specifier, then an error is returned. If
there is no matching entry in _a_r_g_T_a_b_l_e, then the argument is
skipped and returned to the caller.
Once a matching argument specifier is found, Tk_ParseArgv
processes the argument according to the _t_y_p_e field of the
specifier. The argument that matched _k_e_y is called ``the
matching argument'' in the descriptions below. As part of
the processing, Tk_ParseArgv may also use the next argument
in _a_r_g_v after the matching argument, which is called ``the
following argument''. The legal values for _t_y_p_e, and the
processing that they cause, are as follows:
TK_ARGV_END
Marks the end of the table. The last entry in _a_r_g_T_a_b_l_e
must have this type; all of its other fields are
ignored and it will never match any arguments.
TK_ARGV_CONSTANT
_S_r_c is treated as an integer and _d_s_t is treated as a
pointer to an integer. _S_r_c is stored at *_d_s_t. The
matching argument is discarded.
TK_ARGV_INT
The following argument must contain an integer string
in the format accepted by strtol (e.g. ``0'' and ``0x''
prefixes may be used to specify octal or hexadecimal
numbers, respectively). _D_s_t is treated as a pointer to
an integer; the following argument is converted to an
integer value and stored at *_d_s_t. _S_r_c is ignored. The
matching and following arguments are discarded from
_a_r_g_v.
TK_ARGV_FLOAT
The following argument must contain a floating-point
number in the format accepted by strtol. _D_s_t is
treated as the address of an double-precision floating
point value; the following argument is converted to a
double-precision value and stored at *_d_s_t. The match-
ing and following arguments are discarded from _a_r_g_v.
TK_ARGV_STRING
In this form, _d_s_t is treated as a pointer to a (char
*); Tk_ParseArgv stores at *_d_s_t a pointer to the fol-
lowing argument, and discards the matching and follow-
ing arguments from _a_r_g_v. _S_r_c is ignored.
Tk 3
Tk_ParseArgv(3) Tk Library Procedures
TK_ARGV_UID
This form is similar to TK_ARGV_STRING, except that the
argument is turned into a Tk_Uid by calling Tk_GetUid.
_D_s_t is treated as a pointer to a Tk_Uid; Tk_ParseArgv
stores at *_d_s_t the Tk_Uid corresponding to the follow-
ing argument, and discards the matching and following
arguments from _a_r_g_v. _S_r_c is ignored.
TK_ARGV_CONST_OPTION
This form causes a Tk option to be set (as if the
option command had been invoked). The _s_r_c field is
treated as a pointer to a string giving the value of an
option, and _d_s_t is treated as a pointer to the name of
the option. The matching argument is discarded. If
_t_k_w_i_n is NULL, then argument specifiers of this type
are ignored (as if they did not exist).
TK_ARGV_OPTION_VALUE
This form is similar to TK_ARGV_CONST_OPTION, except
that the value of the option is taken from the follow-
ing argument instead of from _s_r_c. _D_s_t is used as the
name of the option. _S_r_c is ignored. The matching and
following arguments are discarded. If _t_k_w_i_n is NULL,
then argument specifiers of this type are ignored (as
if they did not exist).
TK_ARGV_OPTION_NAME_VALUE
In this case the following argument is taken as the
name of a Tk option and the argument after that is
taken as the value for that option. Both _s_r_c and _d_s_t
are ignored. All three arguments are discarded from
_a_r_g_v. If _t_k_w_i_n is NULL, then argument specifiers of
this type are ignored (as if they did not exist).
TK_ARGV_HELP
When this kind of option is encountered, Tk_ParseArgv
uses the _h_e_l_p fields of _a_r_g_T_a_b_l_e to format a message
describing all the valid arguments. The message is
placed in _i_n_t_e_r_p->_r_e_s_u_l_t and Tk_ParseArgv returns
TCL_ERROR. When this happens, the caller normally
prints the help message and aborts. If the _k_e_y field
of a TK_ARGV_HELP specifier is NULL, then the specifier
will never match any arguments; in this case the
specifier simply provides extra documentation, which
will be included when some other TK_ARGV_HELP entry
causes help information to be returned.
TK_ARGV_REST
This option is used by programs or commands that allow
the last several of their options to be the name and/or
options for some other program. If a TK_ARGV_REST
argument is found, then Tk_ParseArgv doesn't process
Tk 4
Tk_ParseArgv(3) Tk Library Procedures
any of the remaining arguments; it returns them all at
the beginning of _a_r_g_v (along with any other unprocessed
arguments). In addition, Tk_ParseArgv treats _d_s_t as
the address of an integer value, and stores at *_d_s_t the
index of the first of the TK_ARGV_REST options in the
returned _a_r_g_v. This allows the program to distinguish
the TK_ARGV_REST options from other unprocessed options
that preceeded the TK_ARGV_REST.
TK_ARGV_FUNC
For this kind of argument, _s_r_c is treated as the
address of a procedure, which is invoked to process the
following argument. The procedure should have the fol-
lowing structure:
int
_f_u_n_c(_d_s_t, _k_e_y, _n_e_x_t_A_r_g)
char *_d_s_t;
char *_k_e_y;
char *_n_e_x_t_A_r_g;
{
}
The _d_s_t and _k_e_y parameters will contain the correspond-
ing fields from the _a_r_g_T_a_b_l_e entry, and _n_e_x_t_A_r_g will
point to the following argument from _a_r_g_v (or NULL if
there aren't any more arguments left in _a_r_g_v). If _f_u_n_c
uses _n_e_x_t_A_r_g (so that Tk_ParseArgv should discard it),
then it should return 1. Otherwise it should return 0
and TkParseArgv will process the following argument in
the normal fashion. In either event the matching argu-
ment is discarded.
TK_ARGV_GENFUNC
This form provides a more general procedural escape.
It treats _s_r_c as the address of a procedure, and passes
that procedure all of the remaining arguments. The
procedure should have the following form:
int
_g_e_n_f_u_n_c(_d_s_t, _i_n_t_e_r_p, _k_e_y, _a_r_g_c, _a_r_g_v)
char *_d_s_t;
Tcl_Interp *_i_n_t_e_r_p;
char *_k_e_y;
int _a_r_g_c;
char **_a_r_g_v;
{
}
The _d_s_t and _k_e_y parameters will contain the correspond-
ing fields from the _a_r_g_T_a_b_l_e entry. _I_n_t_e_r_p will be the
Tk 5
Tk_ParseArgv(3) Tk Library Procedures
same as the _i_n_t_e_r_p argument to Tcl_ParseArgv. _A_r_g_c and
_a_r_g_v refer to all of the options after the matching
one. _G_e_n_f_u_n_c should behave in a fashion similar to
Tk_ParseArgv: parse as many of the remaining arguments
as it can, then return any that are left by compacting
them to the beginning of _a_r_g_v (starting at _a_r_g_v[0]).
_G_e_n_f_u_n_c should return a count of how many arguments are
left in _a_r_g_v; Tk_ParseArgv will process them. If _g_e_n_-
_f_u_n_c encounters an error then it should leave an error
message in _i_n_t_e_r_p->_r_e_s_u_l_t, in the usual Tcl fashion,
and return -1; when this happens Tk_ParseArgv will
abort its processing and return TCL_ERROR.
FLAGS
TK_ARGV_DONT_SKIP_FIRST_ARG
Tk_ParseArgv normally treats _a_r_g_v[_0] as a program or
command name, and returns it to the caller just as if
it hadn't matched _a_r_g_T_a_b_l_e. If this flag is given,
then _a_r_g_v[_0] is not given special treatment.
TK_ARGV_NO_ABBREV
Normally, Tk_ParseArgv accepts unique abbreviations for
_k_e_y values in _a_r_g_T_a_b_l_e. If this flag is given then
only exact matches will be acceptable.
TK_ARGV_NO_LEFTOVERS
Normally, Tk_ParseArgv returns unrecognized arguments
to the caller. If this bit is set in _f_l_a_g_s then
Tk_ParseArgv will return an error if it encounters any
argument that doesn't match _a_r_g_T_a_b_l_e. The only excep-
tion to this rule is _a_r_g_v[_0], which will be returned to
the caller with no errors as long as
TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified.
TK_ARGV_NO_DEFAULTS
Normally, Tk_ParseArgv searches an internal table of
standard argument specifiers in addition to _a_r_g_T_a_b_l_e.
If this bit is set in _f_l_a_g_s, then Tk_ParseArgv will use
only _a_r_g_T_a_b_l_e and not its default table.
EXAMPLE
Here is an example definition of an _a_r_g_T_a_b_l_e and some sample
command lines that use the options. Note the effect on _a_r_g_c
and _a_r_g_v; arguments processed by Tk_ParseArgv are elim-
inated from _a_r_g_v, and _a_r_g_c is updated to reflect reduced
number of arguments.
/*
* Define and set default values for globals.
*/
Tk 6
Tk_ParseArgv(3) Tk Library Procedures
int debugFlag = 0;
int numReps = 100;
char defaultFileName[] = "out";
char *fileName = defaultFileName;
Boolean exec = FALSE;
/*
* Define option descriptions.
*/
Tk_ArgvInfo argTable[] = {
{"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
"Turn on debugging printfs"},
{"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps,
"Number of repetitions"},
{"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName,
"Name of file for output"},
{"x", TK_ARGV_REST, (char *) NULL, (char *) &exec,
"File to exec, followed by any arguments (must be last argument)."},
{(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL,
(char *) NULL}
};
main(argc, argv)
int argc;
char *argv[];
{
...
if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) {
fprintf(stderr, "%s\n", interp->result);
exit(1);
}
/*
* Remainder of the program.
*/
}
Note that default values can be assigned to variables named
in _a_r_g_T_a_b_l_e: the variables will only be overwritten if the
particular arguments are present in _a_r_g_v. Here are some
example command lines and their effects.
prog -N 200 infile # just sets the numReps variable to 200
prog -of out200 infile # sets fileName to reference "out200"
prog -XN 10 infile # sets the debug flag, also sets numReps
In all of the above examples, _a_r_g_c will be set by
Tk_ParseArgv to 2, _a_r_g_v[0] will be ``prog'', _a_r_g_v[1] will be
``infile'', and _a_r_g_v[2] will be NULL.
Tk 7
Tk_ParseArgv(3) Tk Library Procedures
KEYWORDS
arguments, command line, options
Tk 8
